Safeguarding the past, present and future of RISC OS for everyone

How to build RISC OS (changes)

Showing changes from revision #19 to #20: Added | ~~Removed~~

h6. [[Developer documentation]]
h6(. » How to build RISC OS
Whether you want to build the RISC OS printer stack, the disc-based software or a whole ROM image, the process is pretty much the same:
# download and install the build sources
# initialise your build directory
# select the correct environment
# start the build process
# check the build log for problems
h3. Set up your build directory
h4. Step 1. Download and extract the source code
The ROOL web site has a number of archives full of source code and other build components for producing a particular target. Here are some examples:
pre. BCM2835Dev - the ROM build for all variants of Raspberry Pi (Zero, Compute, Pi 1, Pi 2, Pi 3)
DiscDev - the RISC OS 5 disc image build, with boot sequence, applications, etc.
IOMDDev - the ROM build for RiscPC- and A7000-type machines (those with the old IOMD chipset)
OMAP3Dev - the ROM build for new OMAP 3 (ARMv7) based machines (Beagle Board, Touch Book, etc.)
OMAP4Dev - the ROM build for new OMAP 4 (ARMv7) based machines (Panda Board, Panda Board ES, etc.)
TitaniumDev - the ROM build for Sitara AM5728 based machines (Elesar Titanium, RapidO-Ti, TiMachine)
TungstenDev - the ROM build for Intel 80321 based machines (Iyonix PC)
There is documentation if you want to find out more about building RISC OS from git. See the [[Beginner's guide to ROM builds]] page for more information.
Before you can do a build, you will need the RISC OS build tools. If you don't already have it, this is available from the RISC OS Open site "here":/content/sales. Unfortunately, this is a commercial product and it is not yet possible for RISC OS to be built using a free toolchain such as GCC. This is because the RISC OS source code and the toolchain were developed side-by-side so the former relies on a lot of unique features in the latter.
Before you can do a build, you will need the RISC OS build tools. If you don't already have them, these are available to buy from the RISC OS Open site "here":/content/sales/dde. It is not yet possible for RISC OS to be built using a free toolchain such as GCC, this is because the RISC OS source code and the toolchain were developed side-by-side so the former relies on a lot of unique features in the latter.
Assuming you already have the build tools installed on your RISC OS machine, you simply need to download the appropriate archive, e.g. the OMAP ROM build, decompress it and extract the contents. ROOL provide a RISC OS application called "UnTarBZ2":/content/downloads/other-zipfiles which can be used to decompress and extract the archive contents. You can also decompress the archives (transform them from a .tar.bz2 into a .tar) using the bunzip2 tool on Linux or a tool such as "7-zip":http://www.7-zip.org/ on Windows.
At this point, the build has been extracted into a directory on the RISC OS machine. In this document, we will assume that you've put it here:
pre. ADFS::HardDisc4.$.RISCOS
and that you already have the RISC OS build tools installed here:
pre. ADFS::HardDisc4.$.AcornC/C++
~~Your build directory which will contain some or all of the following subdirectories:~~
~~pre. apache - source code published under the Apache 2.0 licence~~
~~bsd - source code published under a BSD-like licence~~
~~cddl - source code published under the CDDL licence~~
~~gpl - source code published under a GPL licence~~
~~mixed - source code published under multiple licences~~
~~Prepare - a tool to initialise the build directory~~
~~Products - contains 'Products' files (described later)~~
You are now just two simple steps away from being able to start the build process.
h4. Step 2. Initialise the build directory
In the RISC OS filer, navigate into the "ADFS::HardDisc4.$.RISCOS.Prepare" directory and run (by double-clicking) the "!Run" file. This will launch the build initialisation process. You should follow the on-screen prompts and if you're not sure of the correct answer to give to a question, just select "Yes".
In the RISC OS filer, navigate into the "ADFS::HardDisc4.$.RISCOS.Apps.!Prepare" and run (by double-clicking) it. This will launch the build initialisation process. You should follow the on-screen prompts and if you're not sure of the correct answer to give to a question, just select "Yes".
Even easier is to tick *Prepare sources* option in the UnTarBZ2 window so after decompressing the archive it runs "Prepare" for you.
h4. Step 3. Start the "Builder" application
The Builder application is a graphical user interface front end for the build process and is very useful (if not essential) if you want to build more than a single component in one go. The "Prepare" process will normally start Builder automatically, but if it doesn't, you can find and run it from here:
pre. ADFS::HardDisc4.$.RISCOS.Apps.!Builder
When it's running, you will see the Builder icon on the iconbar. You will probably need to set up Builder so that it knows where your build tree is. This is pretty simple and just involves opening the menu over the Builder icon and selecting "Register build tree". Drag the build directory (e.g. RISCOS in this case) to the registration window and click "Save". Now you are ready to go...
When it's running, you will see the Builder icon on the iconbar. You will probably need to set up Builder so that it knows where your build tree is. This is pretty simple and just involves opening the menu over the Builder icon and selecting "Register build tree...". Drag the build directory (e.g. RISCOS in this case) to the registration window and click "Save". Now you are ready to go...
h3. Select a build environment
One single build tree may be used to build a number of different targets. To decide which one it will generate, you need to select an "environment". There are quite a few to choose from, including:
pre. ROOL.Disc
ROOL.IOMD32
ROOL.OMAP3
ROOL.Tungsten
In the following example, we will build using the "OMAP3" environment, as this is the one for the OMAP ROM image, which is the source tree that we downloaded.
Note: a build directory may list all of these environments as being available, but the build for any other environment will likely fail, e.g. trying to build a Tungsten ROM image from the OMAP archive because the archive only contains source code for the components used for a very specific target in order to keep the size down. In theory, you could have a build directory which includes the source code to _every_ RISC OS component, in which case most, if not all, of the environments could be selected and then their target built.
So to recap a few steps:
* Run !Builder and it will appear as an icon on your iconbar.
* The first time you run it, you will need to tell it where your build directory is.
* To do this, ADJUST (right) click on the iconbar icon.
* To do this, *Adjust* (right) click on the iconbar icon.
* This opens the "Register build directories" window.
* Drag and drop your "RISCOS" build directory into the window.
* Click "Save".
Now Builder is set up and will remember this information the next time you start it.
* SELECT click on the iconbar icon
* *Select* (left) click on the iconbar icon
* The "Build options" window will open with your build directory listed.
* Click on the menu icon or "Environment".
* A menu of build environments should open, including "ROOL.OMAP3".
* (If you don't get this menu, you have registered the wrong directory as a build directory. Use the iconbar menu and re-register the correct directory.)
* Select the "ROOL.OMAP3" environment.
h3. Start the build process
Once you have selected your build environment in the Builder window, you then need to select the build options for a particular build. In this example, you will want to select:
* "List"
* "Clean"
* "Clean all"
* "Export headers"
* "Export libraries"
* "Export resources"
* "Make ROM"
* "Install ROM"
* "Join ROM"
You can safely ignore the section of this window for "Version numbering"; it is very rare that you will ever want to use this section (if ever).
Now you can click on the "Build" icon and a task window should appear containing lots of output from the build process as it runs. There will also be lots of disc activity - don't be surprised if a build such as this takes half an hour or more to complete. Some warnings may also appear in a throwback window.
! It is vital that you don't change the currently selected directory (CSD) during the build process as this will cause things to fail to build correctly in strange ways. It is best to leave your machine alone while a build is in progress (although you don't have to!).
h3. Check the build log for problems
This is something of a black art. In the very simplest terms, if the thing you were building has popped out of the build (into "Images" for a ROM image or "Install" for disc-based software) then you're most of the way there.
However, you should still look for significant warnings and errors in the log file. Most errors that matter will be prefixed by:
pre. AMU: ***
so this is a good thing to search for. However, during the "Clean" and "Clean all" phases, there are lots of components which attempt to wipe object files and binaries that might not exist. This can lead to lots of:
pre. AMU: *** Not found ***
errors. These can safely be ignored. Hopefully, all of these components will be fixed over time so that they no longer do this. The best advice is to ignore errors from these phases and search forward in the log from the start of the next phase, e.g.
pre. Starting phase export_hdrs ...
Some of the most serious errors are:
pre. AMU: Don't know how to make '...'
and:
pre. AMU: *** exit (1) ***
then you know that some component has failed to build and there is something very wrong.
There's another error (warning actually) which can lurk like a time bomb in your build. I can't remember exactly what it says, but I think it's something like this:
pre. ARM Linker: (attribute difference = {32bit}).
This is basically saying that some of a C program is built 32-bit neutral and other bits aren't. This can lead to things appearing to be fine until you are running the program and you hit the bit of code which might not be 32-bit on a 32-bit system. Bang!
It is beyond the scope of this document to explain how to fix a build when you do find these errors but RISC OS Open will do their best to ensure that all of the 'standard' builds work before they are released.
h3. Further information
You're probably wondering what is going on behind the scenes when you do a build. This is a quick overview of the underlying process so that you can create your own builds.
There is a central file called:
pre. BuildSys.ModuleDB
this contains a list of every source component in the build and gives it an associated tag so that a given component can be built in a specific way by simply referring to the tag. For example, the "ModuleDB" might contain a couple of lines like:
pre. UK ASM apache.RiscOS.Sources.Internat.Territory.Module Internat UK
Italy ASM apache.RiscOS.Sources.Internat.Territory.Module Internat Italy
So if we want to build the UK territory module, we can simply refer to the "UK" tag. Using the "Italy" tag will build the Italian territory module from the same sources.
So where are these tags used? The tags required to build a particular product are listed in a "components" file. These are all stored in the following directory:
pre. ADFS::HardDisc4.$.RISCOS.BuildSys.Components
You will see that there are already some components files in the "ROOL" subdirectory. You can treat these as a template if you want to create your own components file for a product. Note: you can pass build parameters to a component in this file, and you can list the same component several times with different parameters.
The "ROOL.Disc" components file lists the "DesktopBoot" tag twice:
pre. DesktopBoot -options INSTDIR=<Install$Dir>.HardDisc4 COMPONENT=Boot
DesktopBoot -options INSTDIR=<Install$Dir>.HardDisc4.Utilities COMPONENT=ResetBoot
in order to build different aspects of that component and put them into a different place in the resulting build.
Each components file needs to have a complementary "Env" file in the "Env" directory. This is an Obey file which sets certain environment variables so that the build system knows which components file you are wanting to build, where the root of your build directory is, etc.
Thus, you will find inside Env the following Obey files:
pre. Env.ROOL.Browse
Env.ROOL.BuildEnv
Env.ROOL.Disc
Env.ROOL.Printers
It is these Obey files that !Builder runs when you select an environment from its menu and that menu is built by scanning the "Env" directory when you have selected your build directory in the main window.
During the build process, all of the output which appears in the task window is also spooled into a text file. This file is placed into:
pre. BuildSys.Logs
and has an unique name (which is adjusted each time you do a build so that older builds don't get their logs overwritten straight away). The precise format of the log file name is actually quite complicated; suffice it to say, if you want to create your own product, you will probably need to speak to the team at RISC OS Open in order to get your product allocated.
h3. What's next?
Well, there are a million and one things that we could write about doing builds but rather than bore you to death with all that, we've put together a [[Build FAQ]] page which covers all of the most common questions.
But for those of you who really love being bored to death, there's some additional information available on the [[Developer's guide to RISC OS builds]] page (covering exciting topics such as what a component or environment is) and the [[Builder]] page (for information about what all of Builder's pretty buttons do).